##############################################################################
###+---------+################################################################
#+-| I_VAL() |-------------------------------------+##########################
#| +---------+ Converts str_number to a LONG value |##########################
#+-------------------------------------------------+##########################
##############################################################################
##############################################################################
#+--| Summary |----------------+##############################################
#|     #INCLUDE string.hdr     |##############################################
#+-----------------------------+##############################################
##############################################################################
##############################################################################
#+--| Syntax |-------------------------------+################################
#|     FUNCTION LONG i_val PROTOTYPE         |################################
#|      PARAMETERS CONST CHAR str_number     |################################
#+-------------------------------------------+################################
##############################################################################
##############################################################################
#########+---| Description |-----------------------------------------+########
#########| The i_val() function converts str_number to a LONG value. |########
#########| i_val() continues to convert the character string until   |########
#########| the end of the string or a non-numeric value is reached.  |########
#########| If no valid number is contained within the string,        |########
#########| i_val() returns zero.                                     |########
#########| --------------------------------------------------------- |########
#########| The i_val() function removes any preceding tabs or spaces |########
#########| from the string str_number.                               |########
#########+-----------------------------------------------------------+########
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Any non-numeric character terminates i_str()        |#########
#########| *    processing, not just white space.                   |#########
#########|                                                          |#########
#########| ? i_val( "1234P" )   ?? 1234 is printed                  |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    Convert a command line parameter to a number.       |#########
#########|                                                          |#########
#########| VARDEF                                                   |#########
#########|     INT     iterations      && Although i_str() returns  |#########
#########|                             &&  a LONG, FORCE compiler   |#########
#########|                             &&  converts the result to   |#########
#########|                             &&  an INT automatically     |#########
#########| ENDDEF                                                   |#########
#########|                                                          |#########
#########| PROCEDURE force_main                                     |#########
#########|  PARAMETERS CONST CHAR(127) command_line                 |#########
#########|                                                          |#########
#########|     iterations = i_str( ltrim( command_line ) )          |#########
#########|     DO WHILE iterations > 0                              |#########
#########|                                                          |#########
#########|     {...}                                                |#########
#########+----------------------------------------------------------+#########
##############################################################################